GlassFish - World's first Java EE 7 Application Server


Felix and Equinox framework configurations are stored in following files in a GlassFish installation:

glassfish/osgi/felix/conf/config.properties

and

glassfish/osgi/equinox/config/config.ini

respectively. As you can observe, these files are part of installation itself and hence suffer from following issues:

  • We have two separate configuration files for two frameworks with a lot of duplication. So, it adds to maintenance overhead.
  • The above files being part of installation are controlled by IPS packaging system, so any change made by user gets overwritten when an update to the file takes place by IPS.
  • In a very controlled production environment, GlassFish Administrators may not have sufficient privileges to edit files which are part of installation directory. They may only have privileges for the domain they are in charge of.
  • Last, but not the least, all domains sharing the same installation are forced to use the same configuration. This is not a very common use case, but possible never-the-less.

None of these issues were unknown when we had decided to keep the configuration in those files respective places. Then why did we do so in the first place?

  • When we embraced OSGi in GlassFish project 3-4 years ago, there was no standard API to launch an OSGi framework. Framework launcher API was introduced in OSGi R4.2 spec. Absence of a standard launching API made us write separate laucher for each OSGi framework. We leveraged each framework's existing launchers in GlassFish code and it was just easier to have the respective launchers configured in a framework specific way.
  • In the initial days, due to lack of documentation in our end, we anticipated OSGi-aware developers to be able to leverage their familiarity with respective OSGi frameworks to configure the OSGi runtime used by GlassFish. So, our file layout reflected a typical Felix or Equinox zip distribution.
  • We did not anticipate users having to modify these files.

So, what changed since then:

  • We have already moved to using the new standard launcher API since GlassFish 3.1.
  • We now have more documentation available.
  • We have come across some real use cases for users having to modify OSGi configuration. The most common requirement here is to disable some optional features like felix remote shell.

To address the aforementioned short-comings, we propose some changes to the location of OSGi configuration information and how we allow users to customize it. Given below is a proposal based on current requirement and relative priority of the issue:

Merge Felix and Equinox configuration into a single file called osgi.properties and place it under installRoot/config/, a directory where other installation specific configuration files are stored. Allow it to be replaced by a user supplied file with same name in instanceRoot/config/. This is similar to how config-files from cluster-admin.jar is handled. An advantages of this approach is that when a change to the file is necessary from development, the file can just be changed via an update without having to write special upgrade code. However, users that have provided their own file will not get the update (just like with config-files). Since the format of this file follows standard properties file format, users can use their favorite OS tools like vim/sed to configure the content of this file. Also allow user to override using system properties in domain.xml, so that for most common cases, they don't have to modify this config file at all. See GLASSFISH-17250 for system property override.  

This proposal has now been implemented in both 3.1.2 and 4.0 branch. See https://github.com/javaee/glassfish/issues/17355 for check-in details.

Alternatives:

  1. Merge Felix and Equinox configuration into a single file called osgi.conf and place it under instanceRoot/config/. The source for the file would need to be in installRoot/lib/templates and create-domain would need to be modified to copy it to the domain. Also, the file name would need to be added to the config-files file so that it gets sync'd to instances. Whenever this file is changed, the upgrade code would need to take care of propagating the change to all domains. One drawback of this approach is that there is a large amount of configuration data in this file that users typically do not need to modify, but since the data is in the domain, the upgrade code has to take care of updating the file. 
  2. Keep the merged OSGi configuration in domain.xml itself. This would allow user to configure using generic asadmin get/set commands as well, but for those generic commands to be really useful, we have to design the schema for these elements carefully, as some of the entries have rather long values. Moreover, this configuration is consulted during bootstrapping only, hence having to read them from domain.xml can unnecessarily complicate the bootstrapping process. So, this alternative is not considered.
  3. Similar to alternative #1, keep the merged osgi.conf in the binary.  However, put it in glassfish.jar so it is somewhat hidden from users. Provide a way to override what is in the file using system properties. These properties can be set in the domain.xml jvm-options settings so that they are per-config (and therefore per-cluster or per-instance), and the launcher already sets the properties before bootstrap so the bootstrap problem of alternative #2 is avoided. The specific properties that can be set by the user need to be specified, but here is an initial suggestion:
    1. org.glassfish.osgi.conffile - overrides the file entirely.  Value is a pathname relative to the config directory.  
    2. org.glassfish.osgi.enable-shell - if true, turns on the OSGi shell
    3. org.glassfish.osgi.optional-bundles - list of optional bundles to start
    4. (maybe) org.glassfish.osgi.override.propslist - list of properties to be overridden from the config file,
                     org.glassfish.osgi.override.prop.<propname> - overridden property value
      The idea here is to capture the most frequently needed OSGi modifications that are needed by typical GlassFish users, but at the same time allowing everything to be customized if absolutely needed. This approach will cause upgrade issues as well as issues for embedded glassfish.